home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Night Owl 6
/
Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso
/
008a
/
pandor23.zip
/
PANDORA.DOC
< prev
next >
Wrap
Text File
|
1992-01-03
|
47KB
|
1,069 lines
User Guide to Pandora
For version 2.3
Pete Maclean [75776,660 on CompuServe]
Copyright 1991 Pete Maclean.
This document comprises a introduction to Pandora plus a summary of what is new
in version 2.x. As a user manual, it is not intended to substitute for my
original article describing the program, then called PAN, that was published in
PC Magazine (Volume 9, Number 9, May 15 1990).
Pandora is a scripting program for automating the operation of other programs.
To make use of Pandora it is necessary to do a little programming in Pandora's
script langauge. Commands are provided to load and run programs, to feed
programs simulated keyboard input, to interact with a user, and to detect what a
program is doing primarily by checking what is displayed on the screen.
Pandora can be used either to set up a program to run all by itself, even in the
middle of the night, or to provide a user with a modified user interface to a
program. It also has application in testing programs in development.
Pandora's script commands are completely described below.
For anyone proposing to use Pandora it is vital to be aware of certain
restrictions imposed. Most of these restrictions reflect original design
decisions made to keep the project within manageable bounds and the program to a
reasonable size. The precise limitations are:
(1) Pandora is designed to be used only with text-mode programs. It is not
impossible to use it with graphics programs -- one user has very succesfully
done so -- but certain commands will be useless with graphics-mode video output
and there are no facilities oriented to graphics.
(2) It is very difficult to use Pandora to automate memory-resident
applications. This is not so much because of limitations in Pandora but because
the design of DOS makes it nearly impossible. If you want to use Pandora with a
TSR program, do try -- you may be lucky -- but be prepared to find that it's
hopeless.
(3) It is difficult to use Pandora with remote-control programs such as Carbon
Copy, Takeover, Close Up, Remote2, and pcANYWHERE. This is unfortunate because
a lot of people have wanted to do so, but the fact is that such programs seize
control of the PC at such a low level that Pandora just cannot slide in
underneath in order to work its magic in the normal way. Despite this warning,
there are some people who have been successful so, again, give it a try if you
will but be cautious.
(4) Pandora does not work with Windows programs. It can, however, be used as
normally with DOS applications that are launched from Windows.
(5) Pandora does not work with CIM, the CompuServe Information Manager. This
is because CIM was intentionally designed and written in a manner that thwarts
its use with programs like Pandora.
Controlling Programs with Pandora
----------- -------- ---- -------
This section describes how Pandora operates. The discussion is necessarily a
little technical but an understanding of the principles involved is essential
to making effective use of the utility. I suggest that you study this once you
have played with Pandora a little and have gained a sense of what it can do, but
before you embark on writing any Pandora scripts.
DOS provides support for two types of program: transient programs and TSRs
(memory-resident programs). Transient programs include all those regular
applications that you use such as word processors, spreadsheet programs, etc.
When you run a transient program, it takes primary control of the PC and
normally retains that control until you terminate it. The most obvious aspect
of this control is that the program essentially owns the screen and keyboard.
DOS allows only one transient program to run at a time but compensates to a
small degree for this limitation by allowing one transient program to execute
another in a nested fashion. The original program becomes dormant after
starting up a second program, then regains control after that second program
quits. You may be familiar with the idea of "shelling out" of an application, a
facility implemented by means of this capability. Since the dormant program
remains in memory, the degree to which this nesting can be done is severely
limited by the amount of program memory available.
Pandora works by running as a transient program itself, and then executing
another program (or a sequence of programs). Once it has has started a "child"
program, Pandora does not, however, go dormant; rather it plays some tricks
normally used by TSRs to retain a measure of control so that it can act in the
role of a "puppeteer" to the child.
A Pandora script, at its simplest, covers three phases of operation:
1. Loading a child program and otherwise preparing for its execution.
2. Running the child program while exerting control over its actions.
3. Terminating the child or waiting for it terminate, and cleaning up
after it.
In a Pandora script you set a child program running by means of the Go command.
From then on until the child dies there are two threads of execution proceeding:
the child itself and the thread represented by Pandora performing the commands
that you have written for it. Control alternates back and forth between these
two threads and the key to successful use of Pandora scripting is managing
synchronization between the two.
Beyond the "Go" point Pandora can interact with the child in one of two ways:
asynchronously or synchronously.
Pandora's primary means of asynchronous interaction is feeding simulated
keyboard input to the child. Pandora stuffs characters into the BIOS keyboard
buffer and the child reads them in its own time. This is asynchronous because
there is no synchronization between Pandora's "feeding" the characters and the
child's "eating" them.
Asynchronous character feeding works a lot of the time but there are also
situations where synchronization is necessary. Consider an application that
displays a prompt for the user to type something and, at the point of displaying
that prompt, flushes the keyboard buffer -- that is, discards any waiting input
to be sure that the characters it processes are fresh and pertinent. If Pandora
is to respond to the prompt then it must first wait for it to appear on the
screen.
Synchronization is achieved by a set of commands with names starting "Wait".
Each such command instructs Pandora to wait for some event before proceeding
with further commands. For this reason, most Wait commands are valid only
during the child-execution phase. (One partial exception is WaitUntil which can
be invoked anywhere in a script to delay until a given time of day.)
To further enhance synchronization between Pandora and its child, several other
commands have been added, such as IfScreen which tests for the presence of a
string on the screen.
Version 2
------- -
Many of the changes in this second-generation Pandora arose from my realization
that, in version 1, there was not a sufficiently clear distinction between
commands that had synchronous effects and those that had asynchronous effects
[see the previous section]. The changes made in version 2 may "break" some
existing Pandora scripts but only trivial modifications should be necessary to
fix them. (To be precise, it may be necessary to change some GetKey commands to
WaitKey, some Pause commands to WaitPeriod, and no more.)
The biggest problem lay in the GetKey command. Although the documentation never
made this fact sufficiently clear, GetKey operated asynchronously. That meant
that a GetKey caused Pandora to wait for the user to press a key before
continuing (with its next command). GetKey had no effect on the child which
would continue to execute indefinitely.
GetKey has been recoded to operate synchronously. Now when Pandora reaches a
GetKey, it stops the child and waits for the user to press a key. Nothing
happens until that keypress is made.
The new command, WaitKey, has been added to do what GetKey did previously. The
name "WaitKey" ties the operation to all the other Wait commands which have
similar effects. A Wait command causes Pandora to wait; the child continues to
run.
Synchronization has also been facilitated by the addition of the Kill and
OnDeath commands. The former allows Pandora to forcibly terminate a child. I
had not provided that capability before because I had not understood how to do
it. OnDeath lets you synch up a script with a child that terminates
asynchronously. See Pandora Commands for more.
Pandora now supports BIOS Enhanced Keyboard Services. This allows it to operate
with programs such as WordPerfect with which it was not compatible previously.
Finally, you will find several other new commands that I have not had occasion
to mention above. VideoFore and VideoBack, for example, let you set screen
colors more easily. ScreenWrite and ScreenRead allow you to save and restore
screen images to create slideshows or other similar effects. PassKey enables
you to filter the keystrokes sent from the keyboard to an application.
Version 2.3 saw the introduction of the CtrlBreak command and a necessary
redesign of the Break On/Off command.
******************************************************************************
*
Pandora Commands
------- --------
(for Pandora v2.2 and later versions)
by Pete Maclean [CIS: 75776,660]
Copyright 1991 Pete Maclean.
This provides documentation on writing scripts for Pandora (originally
published as PAN). Please note that many commands have been added since the
PAN article was published in PC Magazine. The behavior of a few other commands
has been changed slightly.
Commands are written one per line with any amount of white space (blanks and
tabs) thrown in before and between fields. Each command starts with a keyword
such as "Output" or "Label". Keywords may be written in any mixture of upper
and lower case. String arguments may be delimited by any non-blank character
although for readability double quotes are suggested.
You can include comment lines in Pandora scripts. Pandora treats any line that
begins with an asterisk as commentary, for example:
* This is a comment line that Pandora ignores.
As is acknowledged in many of the command descriptions, Pandora does little
error checking. If a script does not do what you expect, consider the
possibility that there is some error that a compiler or other typical language
processor would catch but which Pandora does not.
Command Groups
------- ------
Commands fall into functional groups as follows:
Loading, starting and terminating programs: Load, IfLoad, Go, KillChild,
OnDeath, WaitChild, Env, SetMemory.
Simulating keyboard input to programs: CtrlBreak, Key, KeyFile, OpenKeyFile,
TypeRate.
Displaying text on the screen: Cursor, Output, ReadScreen, Screen, Mode, Video,
VideoBack, VideoFore, Wipe, WriteScreen.
Controlling user interaction with a program: Alt, Ctrl, CapsLock, NumLock,
LeftShift, RightShift, Break, Flush, ScrollLock, Lock, UnLock.
Timing events; Pause, IfAfter, IfBefore, WaitPeriod, WaitUntil.
Script control: Call, Return, If..., Else, EndIf, Jump, Quit.
Detecting program activity: IfScreen, WaitScreen.
Miscellaneous: DOS, Tone.
Command Descriptions
------- ------------
Alt On/Off
(See section on Keyboard Control Commands below.)
Break On/Off
Sets the condition for how Pandora handles a Control-Break. Please
note that the effect of this command was changed in the transition
from Pandora version 2.2 to 2.3.
By default (the condition set by "Break Off") Pandora pays no attention
to a Ctrl-Break. If a child program is running then the child
handles Ctrl-Break according to its design. For many programs, this
key combination serves as an abort signal and DOS provides some facilities
for handling it as such. Programs may, however, treat Ctrl-Break in
other ways.
By issuing a "Break On" command, you tell Pandora to intercept a
Ctrl-Break and use it as a signal to abort processing of the script.
Then, when the user presses Ctrl-Break, Pandora steps out of the way
and leaves the program to continue running as if it (Pandora) were no
longer there. There may be no apparent indication of this happening!
Setting "Break On" can be useful, for example, when you set up a script
to run a program over and over again in a loop. You might do this with
a program that displays the status of something that changes over time
such as the load average on a LAN. Instead of having your script
laboriously intercept every keypress and check for some signal to
terminate, you may be able to just set enable termination by Control-
Break.
Issue a Break command prior to starting the child program. Pandora
will generate an error if it meets a Break while running a program.
Call label
Call coupled with the Return command gives Pandora a primitive
subroutine capability. When Pandora performs a Call command it
pushes a pointer to the next command onto an internal stack. When
a Return is issued that pointer is popped. No system is provided
for passing arguments to a subroutine. Here's an example:
Call procedure
.....
.....
Quit
Label procedure
Output "This message come from a subroutine!"
Return
Warning: This facility is provided as an interim measure. It may
in future be supplanted by a more powerful subroutine mechanism.
I make no guarantee to continue supporting the current facility.
CapsLock On/Off
Simulates toggling the CapsLock key. The argument must be "On" or "Off".
The setting of CapsLock affects keyboard input typed by the user; it
does *not* affect simulated keyboard input generated by the Key command.
To ensure that CapsLock is off when starting a program, for example, use
the command:
CapsLock Off
Ctrl On/Off
(See section on Keyboard Control Commands below.)
CtrlBreak
Simulates the user's pressing Ctrl-Break. Feeding a Ctrl-Break
to a program is accomplished by this command rather than via the
Key command because Ctrl-Break is interpreted as an abort signal
and handled in a special way at a low level in the PC (actually by
the BIOS keyboard driver).
Simulating a Ctrl-Break condition is tricky and this command is known
to not work correctly with certain programs such as Microsoft Flight
Simulator.
Cursor <row> <column>
Repositions the cursor to a location on (or possibly off) the screen.
As with all other commands that refer to screen coordinates, rows and
columns are numbered from zero with the top left corner being row 0,
column 0. The row and column arguments are decoded as decimal integers
and their values are not checked. If an argument is omitted or invalid
(i.e., non-numeric) then a default value of zero is used; *no* error
indication is given. The cursor can be made to "disappear" by moving it
to a location beyond the bounds of the screen, for instance with the
command:
Cursor 25 0
DOS "command"
Runs a copy of the DOS command interpreter to execute the supplied command.
Pandora allows the execution of any command that you can type at the DOS
prompt. It can be used for such purposes as changing the current
directory, getting directory listings, and deleting files. All standard
command options are supported including redirection and batch files.
Here are some examples:
DOS "cd \new"
DOS "del blah.dat"
DOS "E:"
DOS "call batch"
DOS "dir *.exe >tmp"
Don't forget to enclose the command in quotes!
Note: The DOS command is not available while Pandora is running a program.
This facility depends on COMSPEC being defined in the environment table.
Pandora uses the COMSPEC string to find the command interpreter,
COMMAND.COM. If COMSPEC is not defined then the DOS command will fail.
Else
Reverses conditional execution inside an If-EndIf command group.
EndIf
Terminates the effect of an If command (i.e. IfKey, IfLoad, IfScreen,
etc.). Every If must have a matching EndIf.
Env
Several early users had trouble getting Pandora to pass on the desired
environment to its children. To accomodate all needs the Env command
allows you to select between two options. The valid forms of the command
are:
Env Own
Env Master
The "Own" argument tells Pandora to pass on copies of its own environment.
This is the default. The "Master" argument tells Pandora to pass on copies
of the master environment. Note that if you use Pandora's DOS command to
change environment strings, as in:
DOS "Set magic=teapot"
it is the master environment that is affected.
The issue of which environment gets inherited is tricky. If you see no
reason to care then don't worry about it; the default should suit you.
Flush
Flushes the keyboard holding buffer. The Flush command is used mostly
in association with the GetKey command to discard any accumulated key
codes before soliciting a keypress from the user.
GetKey
Waits for the user to depress a key on the keyboard which then becomes
available for testing with the IfKey command or passing on to the child
with Passkey.
See also IfKey, PassKey and WaitKey.
Go "arguments"
Initiates execution of a child program that has been loaded with a Load
or IfLoad command. The child is run as if it had been started from the
DOS prompt with the given argument string.
IfAfter <time>
Tests if the time kept by DOS is equal to or greater than the time given.
The argument should be expressed in the format HH:MM using the 24-hour
system. For example, the following will hold true if it is 10:15 pm or
later:
IfAfter 22:15
IfBefore <time>
Tests if the time maintained by DOS is before that specified. As with the
previous command, the time must be expressed in the form HH:MM where HH is
an hour in the range 0 to 24 and MM is a minute in the range 0 to 59. The
following command, for instance, will hold true if it is earlier than
6:05 am:
IfBefore 6:05
IfExist "file"
This works exactly like DOS' IF EXIST command for batch files. This
example should make it clear:
IfExist "XRB.BAT"
DOS "XRB ABC"
Else
Output "ERROR: Cannot find the batch file XRB.BAT"
Quit
EndIf
IfExist detects the presence of regular files plus hidden and system
files. It does not directly detect subdirectories or volume labels.
Nevertheless, as with the DOS command, you can test if a given
directory exists by testing for NUL within that directory, as in.
IfExist "C:\DOS\NUL
Else
Output "ERROR: You don't have a C:\DOS directory"
Quit
EndIf
IfKey "list"
Tests if the last keypress (that captured by a GetKey command) matches
one of those in the given list. If there is a match the subsequent
commands are executed. If the match fails then command execution is
inhibited until a matching Else or EndIf command is encountered.
The following command, by way of example, would result in a match if
the key in question was any digit:
IfKey "1234567890"
IfKeyFileEOF
Tests for an end-of-file condition on the file opened by the last
OpenKeyFile command and processed by the KeyFile command.
A typical sequence of commands is:
OpenKeyFile "INPUT"
Label keyer
[Wait for some prompt]
KeyFile Line
IfKeyFileEOF
Else
Jump keyer
EndIf
IfLoad "file"
Attempts to load a program into memory for subsequent execution. The
argument supplies the filename in which the extension ("EXE" or "COM")
must be included. Execution of the loaded program does not start until
a Go command is performed. The commands following the IfLoad are
performed if the load is successful; if it fails, the commands following
an Else or EndIf are performed. For example:
IfLoad "c:\program.com"
Output "The program has been loaded successfully!^M^J"
Go
Quit
Else
Output "The program could not be loaded!^M^J"
Quit
EndIf
IfScreen <row> <column> "string"
Checks if the given string appears on the screen at the given position.
(This command, obviously, is closely related to WaitScreen.) For
example:
IfScreen 24 0 "OK"
Jump success
EndIf
IfScreen 24 0 "Error"
Quit
EndIf
checks for two strings that a program may display, and takes appropriate
action for each.
Jump label
Transfers control to the given label (defined in a Label command).
Key "string"
Feeds the given string of characters to the running program by
entering them, one by one, into the keyboard holding buffer. This
simulates a user typing the same characters at the keyboard. This
example has the equivalent effect of a user typing "Yes" then pressing
the Enter key:
Key "Yes[Enter]"
The Key command is valid only while Pandora is running a program.
The rate at which keycodes are fed to the program can be moderated by
means of the TypeRate command.
If you want to feed a Ctrl-Break signal to a program you must do so
using Pandora's CtrlBreak command. It is not possible to issue a
Ctrl-Break with the Key command.
KeyFile Char/Line
KeyFile is a lot like Key but feeds characters read from a file into
the keyboard buffer. Each invocation of KeyFile feeds either a character
or a line from the file opened in an OpenKeyFile command.
Each byte from the file is read as one literal character.
Thus only ASCII and extended-ASCII characters can be fed in this manner;
there is no way to introduce Alt-shifted keys, function keys, etc.
Pandora strips linefeeds from the file and passes everything else. If
any user finds a need to strip other characters, or to not strip linefeeds,
then I shall add a mechanism to permit such.
KeyFile is valid only while Pandora is running a program.
The rate at which keycodes are fed to the program can be moderated by
means of the TypeRate command.
See also IfKeyFileEOF which provides for end-of-file detection.
KillChild
Kills the child program. An error occurs if this command is used when
no program is running.
This command should be seen as a brute-force method of terminating a
child program. If you have the option of feeding the program some
appropriate keystrokes to tell it to quit, then do that instead.
If a program traps any device interrupts then terminating it with
KillChild may result in an error condition that forces a reboot.
This applies, for example, to most communication programs.
Label label
Defines a label that can be used as the object of a Jump command. This
command is a no-operation in most respects.
LeftShift On/Off
(See section on Keyboard Control Commands below.)
Load "file"
Loads a program into memory for subsequent execution. The argument
supplies the filename in which the extension ("EXE" or "COM") must be
included. Execution of the loaded program does not start until a Go
command is performed. Should the load fail for any reason, Pandora emits
a suitable diagnostic and quits. If you want Pandora to maintain
control after a failed load then use IfLoad instead.
Lock
This command locks the keyboard. If you want Pandora to have full control
over keyboard input to the child program then you should use this
command at an appropriate point. Locking the keyboard prevents
user keypresses from getting interspersed with the simulated input
generated by Pandora's Key commands.
After a Lock, the keyboard remains locked until either an Unlock
command is performed or Pandora quits. If the user presses a key while
the keyboard is locked, the system beeps and otherwise the action is
ignored. (In fact, the behavior is identical to that taken by DOS
when the type-ahead buffer is full.)
Mode
Commands such as Screen and IfScreen operate by delving into the video
buffer, that is the block of memory that holds a character-by-character
image of what appears on the screen. When Pandora starts up it determines
the memory address for the current screen buffer and then uses that
same address whenever the need arises. Some programs change the video
mode; in such a case the address of the effective video buffer may
change too. The Mode command forces Pandora to reevaluate the address for the
video buffer.
Very few people will need the Mode command, especially as Pandora offers
so little assistance in automating graphics applications. Should you
write a script and find that WaitScreen commands do not take effect then
consider the possibility that you need to add a Mode command.
NumLock On/Off
Simulates toggling the NumLock key. The argument must be "On" or "Off".
The setting of NumLock affects keyboard input typed by the user; it
does *not* affect simulated keyboard input generated by the Key command.
To ensure that NumLock is off when starting a program, for example, use
the command:
NumLock Off
OnDeath <label>
OnDeath is Pandora's one asynchronous command. It allows you to establish
a label to which control is transferred when a child dies. Here is a
simple example of its use:
Load "program.exe"
Go
OnDeath Obituary
Label Loop
GetKey
IfKey "[Ins]"
Else
PassKey
EndIf
Goto Loop
Label Obituary
...[continued]
This script feeds keyboard input to a program filtering out the Insert
key. When the child terminates, control is automatically switched from
the loop to the command following "Label Obituary".
You can use this form of script in more sophisticated ways to build
application-specific keyboard-macro processors.
OpenKeyFile "filename".
Opens a file for use with the KeyFile command. If the file cannot be
opened then Pandora displays a diagnostic and aborts. The file opened
by this command remains open either until another OpenKeyFile is performed
or until Pandora quits. For further information, see the entry for
KeyFile.
Output "string"
Displays a string on the screen at the current cursor location. The
cursor is updated in the process. The Output command should be used
to display stuff when animating applications that use the screen in a
simple scrolling manner (like DOS utilities). The Screen command, by
contrast, should be used with screen-oriented applications.
Here is an example:
Output "This string scrolls onto the screen.^M^J"
The "^M^J" part stands for a carriage return plus a linefeed.
You may redirect Output to a file in the same way as you would
using redirection on the DOS command line. For example:
Output "This gets written to a file^M^J" > thisfile
Output "This gets appended to a file^M^J" >> thatfile
PassKey
Passes the keycode obtained by the last GetKey or WaitKey to the
child program. GetKey and PassKey can be used in combination to
provide a keyboard macro facility for a program, as in this
example:
Label keyer
GetKey
IfKey "[Alt]M"
Key "This is a macro"
Else
PassKey
EndIf
Jump keyer
These commands can also be used to filter keycdoes to ensure that
selected codes never reach a program.
See also GetKey, Ifkey and WaitKey.
Pause <n> Ticks/Seconds/Minutes
Pauses for the specified period. Permissible times are:
1 - 255 ticks
1 - 255 seconds
or 1 - 60 minutes
A tick refers to the period between clock ticks on a standard PC; such
ticks occur at a rate of 18.2 to a second. The following example
invokes a delay of two and a half minutes:
Pause 2 minutes
Pause 30 seconds
Pandora interprets only the first letter of the units field, looking for
't', 's' or 'm'. If the units field is omitted, Pandora assumes seconds.
PrintScreen
This command, which takes no arguments, has the same effect as pressing the
<PrtSc> key on the PC keyboard. (Internally this invokes interrupt number
5.) It is compatible with PC Magazine's PRN2FILE utility.
Quit
Terminates Pandora. If Pandora has no child running then it quits
immediately. If a child is active then Pandora quits only when
that child quits.
ReadScreen <filename>
Restores a screen image from a file. Use the WriteScreen command to
create suitable files.
Return
Return from a subroutine. (See Call.)
RightShift On/Off
(See section on Keyboard Control Commands below.)
Screen <row> <column> "string"
Writes a string of characters to the screen starting at the character
position defined by the <row> and <column> arguments. The operation is
performed using a direct write to the video buffer. For example:
Screen 10 40 "This appears on line 10 starting at column 40"
Note that for this, as for all purposes in Pandora, rows are numbered
from 0 to 24 and columns from 0 to 79. The video attribute used is that
set by the last Video, VideoFore and/or VideoBack command(s).
ScrollLock On/Off
Simulates toggling the ScrollLock key. The argument must be "On" or "Off".
SetMemory
SetMemory is a command intended for programmers who need to test their
products running in limited amounts of memory. It is likely to be of no
value to most Pandora users. The following command, for example:
SetMemory 100
artificially sets the largest block of free DOS memory to a size of 100
kilobytes. The argument is a decimal number that is interpreted as a KB
count. The effect of a SetMemory lasts until either another SetMemory is
performed or until Pandora exits.
Tone
The Tone command enables you to generate a tone on the PC's speaker.
Normally, it takes two arguments: a frequency and a duration. The
frequency is a number of Hertz between 50 and 15000. Selecting 50 Hz
results in a low buzz while 15000 Hz is sufficiently high-pitched that most
PC speakers will not even succeed in reproducing it. The duration is the
period of time that you want the tone sounded for. Here's an example:
Tone 262 1s
This will generate a 262-Hz tone (that's middle C, I believe) for a period
of one second. The duration argument is expressed in exactly the same way
as an argument to the Pause command. The shortest available duration is
one tick, that is approxiamtely one eighteenth of a second. You can play
some primitive tunes by writing a sequence of Tone commands. (Would
someone volunteer to compose the Pandora theme tune?)
A further option on the Tone command lets you have a tone sounding while
other Pandora commands are executing. If the duration argument is given as
zero (or is simply omitted) the tone will be generated until the next Tone
command is performed. To shut off a tone started in this way, use a Tone
command with a first argument of zero. Here's an example:
Tone 98 0
Output "The tone you are hearing has a frequency of 98 Hz^M^J"
Output "Press any key when you are sick of it!"
GetKey
Tone 0
TypeRate <ticks>
Controls the rate at which characters are fed by the Key command into
the keyboard holding buffer. For most situations setting the TypeRate
to zero is the best choice; then the keys are fed to the animated
program as fast as it will accept them. If you want the user to
clearly see what is being "typed" then set the TypeRate to some number
between 2 and 9. The number represents the count of 18.2-to-a-second
ticks that are forced to pass between each pair of keyed characters.
Unlock
Unlocks the keyboard if it was previously locked by a Lock command. If
the keyboard is not locked then this command does nothing.
Video <attribute>
Sets a video attribute for writes by subsequent Screen commands.
The argument is interpreted as a hexadecimal number. The default screen
attribute (70 hex) is for white foreground and black background.
The Video command is provided for historical reasons. Most users will
prefer to use VideoBack and VideoFore.
VideoBack <background_color>
Sets the background color for subsequent Screen commands. Valid colors
are:
Black, Blue, Green, Cyan, Red, Magenta, Brown and White
VideoFore <background_color>
Sets the foreground color for subsequent Screen commands. Valid colors
are:
Black, Blue, Green, Cyan, Red, Magenta, Brown, White,
Grey, LightBlue, LightGreen, LightCyan, LightRed
LightMagenta, Yellow and BrightWhite
Composite color names must be written as one word, as shown.
VideoNormal
Restores "normal" video after reverse video has been selected by
the VideoReverse command.
VideoReverse
Reverses the foreground and background colors.
WaitChild
Suspends Pandora activity until the child program terminates.
WaitKey
Suspends Pandora activity until the user presses a key. The child
program continues running but is blocked from getting keyboard input.
WaitKey is valid only while a child program is running.
Note the difference between GetKey and WaitKey. If no child is running
then GetKey should be used. GetKey suspends both Pandora itself and
the child program until the user presses a key. WaitKey suspends
Pandora but lets the child run unmolested.
Here's a simple example of the use of WaitKey:
Load "program.exe"
Go
WaitKey
KillChild
This starts up a program and lets it run until the user presses
a key, any key. Obviously this assumes that said program runs
without asking for any keyboard input. WaitKey can be very useful
in scripts written to demo programs.
See also GetKey, IfKey and PassKey.
WaitPeriod <n> Ticks/Seconds/Minutes
Suspends Pandora activity for the specified period of time. The
argument has exactly the same form as that for the Pause command.
Suppose you want to set up a program for people to try at a trade
show. You want to limit each user to running the program for 3
minutes in order to gove plenty of people an opportunity. The
following script will give you an idea of how to do it.
Label next
Wipe
Screen 0 0 "Press any key for a 3-minute try"
GetKey
Load "program.exe"
Go
WaitPeriod 3 minutes
KillChild
Jump next
Note the difference between WaitPeriod and Pause. Pause suspends
both Pandora and the child program (if any) for the given period.
WaitPeriod suspends Pandora but lets the child run. The following
example demonstrates this with a script fragment that runs a
program in slow motion by alternately letting it run for one tick
and then freezing it for three. The effect may be rather jerky.
Label SlowDown
WaitPeriod 1t
Pause 3t
Jump SlowDown
WaitScreen <row> <column> "string"
Waits for the given string to appear on the screen starting at the
given position. Pandora continually searches for the string in the video
buffer. Use this command with care: Pandora will wait forever if
necessary for the string to appear and there may be no way to interrupt
the wait other than by pressing Ctrl-Alt-Del.
WaitUntil <time>
Suspends Pandora activity until the given time of day. Times should be
expressed using 24-hour-clock notation. Thus to wait until 10:15 pm,
one should code:
WaitUntil 22:15
This command may be used in any context, that is with or without
a child program running. When there is no child running you can
abort a WaitUntil by pressing the Escape key.
Wipe
Clears the screen. (A BIOS function is used to do this.)
WriteScreen <filename>
Writes a copy of the current screen image to the named file. The
image can be restored using the ReadScreen command. Note that this
command works only with 25x80-character text-mode screens, and that
the screen attributes are stored along with the characters.
You can create simple slideshows using WriteScreen and ReadScreen.
Keyboard Control Commands
-------- ------- --------
I added some commands so that I could experiment with using Pandora to control
pop-up memory-resident programs with hot keys. The commands are Alt, Ctrl,
LeftShift and RightShift. Each takes an argument of On or Off. The effect of,
for example:
Alt On
is to duplicate pressing the Alt key on the keyboard. Suppose that you have a
memory-resident program that pops up when you press both shift keys
simultaneously; then you can make Pandora pop it up with the commands:
LeftShift On
RightShift On
Note that once you have used such a command, the effect is as if you had pressed
the equivalent key and remained pressing it. To release the key, you must give
a command such as:
LeftShift Off
otherwise you may experience strange keyboard behavior.
Also please note that these commands, like CapsLock etc., affect only the real
keyboard. They have no effect on simulated keyboard input generated by the Key
command.
Wait Commands
---- --------
All of the Wait commands cause Pandora to suspend command processing until some
external event occurs. Normally this is an event triggered by the child program
such as its displaying a certain message on the screen.
Waits allow you to synchronize your Pandora scripts with events in the child
program. It is also possible to synchronize with external events such as the
user pressing a key (WaitKey) or a certain time of day rolling around
(WaitUntil).
Key strings
--- -------
A string provided as an argument to the Key or IfKey command contains symbols
identifying keys on the standard IBM keyboard. With the IfKey command, the
string expresses a list of keys to be matched to the last keypress; the order in
which the keys are expressed is immaterial.
The rules for naming keys are as follows:
Any printable character (except '~' or '[') represents the key that
generates it.
e.g., "ABC..., abc..., 123..., !#$%&*()-=+\|`;:'".,/?><{}"
The caret (^) and open square bracket ([) are used as escape characters
and if intended literally must be doubled.
e.g., "^^ signifies a caret and [[ a bracket."
A named key is represented by the name in square brackets. Here is a
complete list of the key names that Pandora recognizes:
[Esc] [Bksp] [Tab] and [Enter]
[Home] and [End]
[Ins] or [Insert], [Del] or [Delete]
[PgUp] or [PageUp], [PgDn] or [PageDown]
[F1] [F2] [F3] [F4] [F5] [F6] [F7] [F8] [F9] [F10] [F11] and [F12]
Arrow keys are identified as follows:
[Up], [Down], [Left] and [Right]
A pure ASCII or extended-ASCII code, equivalent to that generated at
the keyboard by holding down the Alt key and entering a decimal code on
the numeric keypad, can be indicated by putting the appropriate number
in square brackets.
e.g. "[227] becomes a pi."
Any character may be prefaced by one or more shift indicators:
[Alt], [Ctrl] or [Shift]. The caret is an alternative for [Ctrl].
Literal control characters should not be included in strings. Any
that are present will be ignored. Use the ^[key] or [Ctrl][key] notation.
I acknowledge that this scheme for naming characters is not complete. One
cannot, for example, distinguish between the two Enter keys.
Here are some examples of key names:
[Alt][F10] Alt-F10
[Shift]2 @ (more simply expressed just by @ itself)
[Esc] Esc
^[[ Esc
[Ctrl][Enter] Ctrl-Enter
[3] Ctrl-C (^C would be more usual, however)
^2 Null
Other strings
----- -------
Strings supplied as arguments to commands such as Screen and Output may contain
printable characters representing themselves and control characters expressed in
the common keyboard-equivalent notation. Control-X is indicated by a caret
followed by an X (that is, '^X') for any suitable X. In this notation, carriage
return is '^M' and linefeed is '^J'. A literal caret is expressed by doubling
the character, that is by '^^'.
Some tips for creating Pandora scripts
---- ---- --- -------- ------- -------
Use the Cursor and Output commands with programs, such as DOS utilities, that
write their screen output in scrolling or teletype fashion. Use the Screen
command with programs that do full-screen output.
Don't let yourself get confused by the differences between key strings (used
with Key and IfKey) and character strings (used with other commands). The
latter style of string is a standard in programming but a key string will be new
to many people. Remember that a key string identifies a sequence of codes
generated by keys on a keyboard, including many for which there are no
equivalent characters. In a key string, for example, "[Home]" serves to
identify a particular key while in a character string it represents a sequence
of six characters: [-H-o-m-e-].
Pandora can be used to run a sequence of programs or one program repeatedly.
After one program terminates and Pandora regains control with an OnDeath, Kill
or WaitChild command, another Load and Go can be issued.
Often when you are having trouble debugging a Pandora script, it helps to make
it operate in slow motion by throwing in a TypeRate command with an argument of
10 or 20. A few programs cannot cope at all with keyboard input fed at the
maximum rate Pandora is capable of; with these programs, judicious use of
TypeRate is a must.
Using Pandora with Large Programs
----- ------- ---- ----- --------
If you are animating a large program, you may need to watch the length of your
Pandora script. The presence of comment lines never hurts because they are
stripped off as the script is loaded. Also it never costs to indent commands
because leading whitespace on a line is also removed. Ways of reducing memory
requirements for a script include keeping labels short (say to two characters)
and limiting each field separator to a single character.
With programs that are memory-hogs, occupying nearly all of available low
memory, you may find insufficient space to squeeze in Pandora, small though it
is. You may be tempted to seek a solution in loading Pandora into high memory
(using, for example, DOS 5's LOADHIGH or QEMM's LOADHI) leaving all of low
memory for the application. Unfortunately, because of the way these loaders
operate, this does not work. I am looking for a way around this problem but
have no confidence that I shall succeed in finding one.
Notes
-----
Pandora seems to be incompatible with SUPER PCKWIK. Should you run this
program, do not rely on Pandora working correctly.
The OpenKeyFile, KeyFile and IfKeyFileEOF commands were added in version 1.6. I
do not guarantee that support for these commands will be maintained in future
versions. Equivalent functionality will always be provided but the commands
involved are subject to change.
Sample Scripts for version 2.1 still work with this version.
---------
In the May 16, 1990 issue of PC Magazine, a utility called PAN
was published. PAN is a registered trademark for electronic
services for the entertainment industry owned by the Pan
Network. In the event anyone may have been confused, the
utility -- which continues to be available -- has been
renamed to PANDORA. Further information regarding PAN can be
obtained by contacting THE PAN NETWORK at P.O. Box 162,
Shippack, PA 19474, (215) 584-0300.